fix(types): declare the component-node arm of DashboardComponentSchema.widgets on the TypeScript face - #8296

Fixes #7952

What

DashboardComponentSchema.widgets (packages/types/src/complex.ts) becomes the two-arm union the zod twin has carried since the 2026-08-14 ruling (objectstack#8593): an array of DashboardWidgetSlotComponentSchema | DashboardWidgetSchema, component arm first as in zod/complex.zod.ts. DashboardWidgetSlotComponentSchema is new — extends BaseSchema with type: DashboardComponentWidgetType — and is exported from @object-ui/types (added to the barrel). packages/types/src/zod/complex.zod.ts is untouched. DashboardWidgetSchema is NOT widened with value / icon / trend / trendValue.

Ruling applied as written (director seat, decision batch #68, 2026-09-07, maintainer 「同意」; card comment 5565355483) — not re-opened here.

Spelling choice (the brief asked which and why)

An interface … extends BaseSchema rather than an intersection or a discriminated member:

• it is the one-to-one twin of the zod arm's BaseSchema.extend({ type: z.enum(DASHBOARD_COMPONENT_WIDGET_TYPES) }), and the same shape DashboardComponentSchema itself uses (extends BaseSchema plus a literal type);
• the export is a deliberate authoring-surface decision, not a compiler requirement — measured in this package's own build (declaration + composite, TypeScript 6.0.3): a non-exported arm referenced from the exported DashboardComponentSchema builds exit 0, emits into dist/complex.d.ts as a local interface, and a barrel consumer still writes the node with no name. It is exported so an author can annotate the node the platform accepts (the README teaches it), an intentional asymmetry with the zod twin's non-exported arm, whose docblock records why that const stays private. (Corrected in the patch round: the first version of this bullet claimed TS4033 forced the export — false, per the contract review.)
• BaseSchema's [key: string]: any is the passthrough, so the component's own props reach the compiler through the index signature and never through DashboardWidgetSchema.

Measurements (re-driven before and after; both PM mechanism assumptions measured, not inherited)

Before, on fc32921. The six const schema = { type: 'dashboard', … } blocks of packages/plugin-dashboard/README.md, extracted from the page's own bytes, annotated DashboardComponentSchema and compiled --strict against the source declaration: 6 × TS2561 ('value' does not exist in type 'DashboardWidgetSchema'. Did you mean to write 'values'?) — the card's five across :47 / :177 / :274, plus one in the "Dashboard with Charts" block at :216, which PR #7951 rewrote after the card was measured. Runtime, same shape: DashboardComponentSchema.safeParse ACCEPT, all seven authored keys preserved.

After, on 297b014. Same six blocks, same annotation, same harness: 0 errors. The runtime verdict is unchanged (the zod face was not edited). The edited README "TypeScript Support" block also compiles against the BUILT packages/types/dist/index.d.ts — the check:doc-snippets question, narrowed to the one block this PR edits (exit 0).

Corners, measured on the source after the change (each is also pinned):

The stray-key envelope row is the one cost of a TypeScript union with a passthrough arm. It is recorded in the member's docblock and pinned two-faced (tsc accepts, zod refuses by name) so it reads as a measured limit rather than a hatch; the runtime is the strict face on that corner, as it already is for every BaseSchema slot.

Consumer cost, measured. The arm is assignable to DashboardWidgetSchema, so every (w: DashboardWidgetSchema) callback in plugin-dashboard compiled unchanged (pinned). An UNANNOTATED element read — schema.widgets.map with a bare w reading w.layout, at DashboardGridLayout.tsx:96 / :161, DashboardWithConfig.tsx:155, DashboardEditor.tsx:559 — now resolves through the index signature to any instead of the widget's declared type — it compiles and checks less. Stated in the changeset; not repaired here: it is BaseSchema's own any, the one every SchemaNode consumer already carries, and annotating those sites is a plugin-dashboard / plugin-designer change outside this card's surface.

Pin — packages/types/src/__tests__/dashboard-widget-slot-component-arm-7952.test.ts

Two-faced, enforced by tsconfig.test.json through type-check (objectui#3009): the README shape compiles AND parses with its keys kept; DashboardWidgetSchema still refuses value (an @ts-expect-error that becomes TS2578 if anyone widens it); the arm's type is closed by reference; the slot element IS the two-arm union; the arm is assignable to DashboardWidgetSchema; the discriminated refusals hold on both faces; the envelope corner is recorded as above.

Reverse verification — committed first; run on 297b014 inside the verify lock; script with a restore trap. widgets put back to DashboardWidgetSchema[] (on-disk proof: two-arm spelling 1 to 0, one-arm spelling 0 to 1), then tsc -p tsconfig.test.json: exit 2, 4 errors, all four in the new pin — :82 TS2561 on value, :101 the two-arm Equal collapsing to false, :165 and :184 the two passthrough literals turning into TS2353. Predicted two, measured four: the direction is red as expected, and the extra two are the passthrough-arm literal and the envelope-corner literal, both excess-property errors once the arm is gone. Restore proved by blob hash — git hash-object after restore equals HEAD:packages/types/src/complex.ts (b7571577), git diff HEAD --stat empty. The ablation resolves through the tests' relative ../complex.js imports (source, not dist/), so no build leg was involved.

Gates — final head 297b014; every exit captured to disk before any output was read

验收备注

• noted, not filed: packages/plugin-dashboard/README.md:131 still declares widgets: DashboardWidgetSchema[] in the "Dashboard Schema" block — valid TS (the narrower array is assignable) and it teaches the spec-family usage; left as is.
• noted, not filed: zod-mirror-parity.test.ts's WiderThanDeclared note "widgets is SCHEMA-NODE" is now true of the whole key (the first arm is aligned); rewording it per arm is objectui#8252's census, whose file surface it is.
• filed as objectui#8290: content/docs/api/schema-reference.md's dashboard table teaches colSpan / rowSpan / body as widget keys (all three refused by name — reproducer in the card) and refreshInterval in milliseconds where the renderer multiplies by 1000; that row's widgets type column is also one arm short after this PR — one docs edit, out of this card's surface.

Route

Draft, needs:contract-review (clause ②: a published TypeScript accept set widens; @object-ui/types changeset, minor). Reviewed in-seat before any ready / queue / auto-merge step — none taken here. Related: objectui#8252 (the census ordered by this card's ruling, held behind this PR), objectui#7035 / PR #7951 (the README's docs half), objectui#6002 (the .strict() ruling the refusals rest on).

Implemented in Claude Code session session_01QtGhnU3WnnWyiWeYQhw2aX (PM loop round R1, domain:spec seat).

🤖 Generated with Claude Code

https://claude.ai/code/session_01QtGhnU3WnnWyiWeYQhw2aX

Generated by Claude Code